星火知识库 API 文档 |
您所在的位置：网站首页 › 文档知识库 开源方法有哪些呢怎么写 › 星火知识库 API 文档 |
|
# 星火知识库 API 文档 # 一、服务介绍 星火知识库是基于讯飞星火大模型的知识库问答方案，能够高效检索文档信息，准确回答专业问题，为大模型补充领域知识，让大模型助你高效了解文档内容。 该接口是通过 API 的方式给开发者提供一个通用的 HTTP 接口，基于该接口，开发者可以获取开放平台的星火文档知识库问答能力，方便开发者快速集成。 # 开通授权您可在讯飞开放平台应用控制台 申请开通 API 权限并采购服务量。 # 产品体验基于星火知识库方案 API，我们搭建了星火文档问答 ，供您快速体验功能和效果。 # 接口 Demo示例 Demo请点击 调用示例 下载。 Demo 覆盖部分语言，其他语言请参照下方接口文档进行开发。 欢迎热心的开发者到讯飞开放平台社区 分享你们的 demo。 # 接口要求 内容 说明 传输协议 https/wss 请求地址 1、文档上传：https://chatdoc.xfyun.cn/openapi/v1/file/upload 2、文档问答：wss://chatdoc.xfyun.cn/openapi/chat 3、发起文档总结：https://chatdoc.xfyun.cn/openapi/v1/file/summary/start 4、获取文档总结/概要内容：https://chatdoc.xfyun.cn/openapi/v1/file/summary/query 接口鉴权 签名机制，详情请参照下方鉴权认证 字符编码 UTF-8 响应格式 统一采用 JSON 格式 开发语言 任意，只要可以向讯飞云服务发起 HTTP/WebSocket 请求的均可 文档格式 当前支持 doc/docx、pdf、md、txt 格式文档 文档大小 不超过 20M 文档长度 不超过 100W 字符 # 二、鉴权认证在调用业务接口时，请求方需要对请求进行签名，服务端通过签名来校验请求的合法性。 # 鉴权方法 # 1、设置签名在 HTTP 请求头 Header 或者 WebSocket 接口中设置参数：appId, timestamp, signature 示例： 文档上传接口：在 Http Request Header 中配置以下参数 String appId = "应用ID"； String secret = "应用的秘钥" Long timestamp = System.currentTimeMillis()/1000; String signature = ApiAuthAlgorithm.getSignature(appId, secret, timestamp); request.setHeader("appId",appId); request.setHeader("timestamp",timestamp); request.setHeader("signature",signature); 文档问答接口：通过在请求地址后面加上鉴权相关参数的方式 wss://chatdoc.xfyun.cn/openapi/chat?appId=xxx×tamp=xxx&signature=xxxxxx签名参数说明： 字段名 类型 描述 必须 appId String 应用 ID Y timestamp Long 时间戳，单位: s，与服务端时间相差五分钟之内 Y signature String 签名 Y # 2、签名（signature）生成规则 首先，用应用 ID（appId）和时间戳（timestamp）通过 MD5 算法生成随机授权参数 auth 再使用授权参数 auth 和接口密钥（secret）基于 HmacSHA1 生产签名 signature示例： public class ApiAuthAlgorithm { private static final char[] MD5_TABLE = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f' }; /** * 获取签名 * * @param appId 签名的key * @param secret 签名秘钥 * @return 返回签名 */ public String getSignature(String appId, String secret, long ts) { try { String auth = md5(appId + ts); return hmacSHA1Encrypt(auth, secret); } catch (SignatureException e) { return null; } } /** * sha1加密 * * @param encryptText 加密文本 * @param encryptKey 加密键 * @return 加密 */ private String hmacSHA1Encrypt(String encryptText, String encryptKey) throws SignatureException { byte[] rawHmac; try { byte[] data = encryptKey.getBytes(StandardCharsets.UTF_8); SecretKeySpec secretKey = new SecretKeySpec(data, "HmacSHA1"); Mac mac = Mac.getInstance("HmacSHA1"); mac.init(secretKey); byte[] text = encryptText.getBytes(StandardCharsets.UTF_8); rawHmac = mac.doFinal(text); } catch (InvalidKeyException e) { throw new SignatureException("InvalidKeyException:" + e.getMessage()); } catch (NoSuchAlgorithmException e) { throw new SignatureException( "NoSuchAlgorithmException:" + e.getMessage() ); } return new String(Base64.encodeBase64(rawHmac)); } private String md5(String cipherText) { try { byte[] data = cipherText.getBytes(); // 信息摘要是安全的单向哈希函数，它接收任意大小的数据，并输出固定长度的哈希值。 MessageDigest mdInst = MessageDigest.getInstance("MD5"); // MessageDigest对象通过使用 update方法处理数据， 使用指定的byte数组更新摘要 mdInst.update(data); // 摘要更新之后，通过调用digest（）执行哈希计算，获得密文 byte[] md = mdInst.digest(); // 把密文转换成十六进制的字符串形式 int j = md.length; char[] str = new char[j * 2]; int k = 0; for (byte byte0 : md) { // i = 0 str[k++] = MD5_TABLE[byte0 >>> 4 & 0xf]; // 5 str[k++] = MD5_TABLE[byte0 & 0xf]; // F } // 返回经过加密后的字符串 return new String(str); } catch (Exception e) { return null; } } } # 鉴权结果如果鉴权失败，则根据不同错误类型返回不同 HTTP Code 状态码，同时携带错误描述信息，详细错误说明如下： HTTP Code 说明 错误描述信息 解决方法 401 鉴权参数为空 Invalid Param, Please check header 检查是否设置鉴权参数 401 签名参数解析失败 Signature cannot be verified 检查签名的各个参数是否有缺失是否正确，特别确认下复制的secret是否正确 401 签名校验失败 Signature required 签名验证失败，可能原因有很多。 1. 检查 appId、secret 是否正确。 2.检查计算签名的方法是否正确。 3. 检查时间戳是否正确等等 403 时钟偏移校验失败 Invalid time or time required 检查服务器时间是否标准，相差 5 分钟以上会报此错误 405 应用无效 Invalid Signature 检查该 appId 是否开通授权 # 三、接口列表 # 1、文档上传 # 接口描述上传知识库文档数据，目前支持 doc/docx、pdf、md、txt 格式，单文件大小不超过 20MB，不超过 100W 字符。 # 接口地址 https://chatdoc.xfyun.cn/openapi/v1/file/upload # 请求参数说明 POST，multipart/form-data 字段名 类型 描述 必须 默认值 file MultipartFile 文件 N url String 文件 url （文件和文件 url 必须有一个） N fileName String 文件名称，带后缀。文件用 url 的方式，该字段必传；传 file 的话，该字段可不传 N fileType String 文件类型，目前传固定值"wiki" Y wiki callbackUrl String 文件状态回调地址，文件状态有变动时服务会调用该 url。调用的时候会带上鉴权头，鉴权方式同【接口鉴权】，业务可根据需要是否做鉴权校验 N # 返回参数示例 { "flag": true, "sid": "9746244f046340e2869630e5f6fe8daa", "code": 0, "desc": null, "data": { "fileId": "24c4109a57944997bc6b82661243ef67" } } # 返回参数说明 字段名 类型 描述 code Int 错误码，成功=0 sid String 请求唯一 id，用于问题定位 desc String 结果描述 data Object 返回结果 data.fileId String 返回上传的 fileId # 2、文档问答 # 接口描述对文档/知识库进行问答，流式返回 # 接口地址 wss://chatdoc.xfyun.cn/openapi/chat?appId=xxxx×tamp=xxxxxxxx&signature=xxxxxx # 请求参数说明在请求 URL 上带上参数：appId, timestamp, signature 鉴权生成详情请参照上方鉴权认证 建立连接时，服务端会校验鉴权 # 发送消息格式 WebSocket 建立成功后，即可发送问答消息，消息格式如下： { "chatExtends": { "wikiPromptTpl": "请将以下内容作为已知信息：\n\n请根据以上内容回答用户的问题。\n问题:\n回答:", "wikiFilterScore": 0.82, "temperature": 0.5 }, "fileIds": ["8b1b17171212121212114fd0806"], "messages": [ { "role": "user", "content": "如何理赔" }, { "role": "assistant", "content": "您好，根据您提供的信息，理赔操作指引如下：\n\n1. 登录小程序，点击“理赔申请”。\n2. 选择对应保单。\n3. 上传理赔相关资料。\n4. 填写发票总金额。\n5. 填写银行账户，需精确到支行。\n6. 点击“提交”成功后，返回“理赔服务”界面，点选“理赔查询”，查看理赔进度和申请记录。\n7. 如有需要，点击“查看详情”，查看理赔详情和金额。\n\n请注意，如有严重既往症员工还请和HR部门及时报备沟通，如未及时报备，保险公司不承担相关责任。同时，索赔资料不齐全导致延迟赔付等问题也需要注意。" }, { "role": "user", "content": "家属有什么福利" } ] } 参数说明： 字段名 类型 描述 必须 默认值 fileIds Array 提问问题检索的文件 id 列表，必传 Y messages Array 问答内容列表，按时间正序，最后一条为最新提问 Y messages.role String user 表示是用户的问题，assistant 表示 AI 的回复 Y messages.content String 用户和 AI 的对话内容 Y chatExtends Object 大模型对话自定义扩展字段 N chatExtends.wikiPromptTpl String wiki 大模型问答模板，在某些场景服务默认的 prompt 回答效果不好时，业务可以考虑通过自定义 prompt 来改善。替换的问题标识，替换的文本内容标识 N chatExtends.wikiFilterScore Float wiki 结果分数阈值，低于这个阈值的结果丢弃。取值范围为(0,1] 参考值为：0.80非常宽松 0.82宽松 0.83标准 0.84严格 0.86非常严格。服务会根据问题检索文件列表中内容相关的文段，该值设置的越高，可能丢弃的内容越多，但保留下来的内容越准确；但过高也可能导致无匹配内容 N 0.82 chatExtends.temperature Float 大模型问答时的温度，取值范围 (0，1] ，temperature 越大，大模型回答随机度越高 N # 返回消息格式 客户端发送消息后，服务端处理后会返回消息，格式如下 { "code": 0, "content": "和指南。在此之前，我可以为您", "fileRefer": "{\"b2de1116b590911111119d0f3dbfc8\":[3,7,8]}", "sid": "870b299a48ba46b6b5e4dfbd99fe4497", "status": 1 } # 返回参数说明 参数名 类型 描述 code Int 错误码 ，0 标识成功 content String 回答内容 sid String 会话唯一标识 status Int 会话状态，取值为[0,1,2,99]；0 代表首次结果；1 代表中间结果；2 代表最后一个结果；99 代表引用的文档及文段 fileRefer String 文档引用，status=99 的时候返回；结构是个 Map，key=文件 id，value=引用的文段列表（对应 fileTrunks 的 index）若返回 fileRefer 为空，提示 "抱款，在文档中没有找到与提问相关的内容，请尝试换个问题问问吧。"表示提问未匹配到文档内容，可以降低chatExtends.wikiFilterScore以降低匹配阈值，也可以开启chatExtends.sparkWhenWithoutEmbedding用大模型兜底。 # 3、文档总结 # 接口描述针对单个文档发起内容总结/概要 # 接口地址 https://chatdoc.xfyun.cn/openapi/v1/file/summary/start # 请求参数说明 POST，multipart/form-data 字段名 类型 描述 必须 默认值 fileId String 文件 ID Y # 返回参数示例 { "flag": true, "sid": "9746244f046340e2869630e5f6fe8daa", "code": 0, "desc": null, "data": null } # 返回参数说明 字段名 类型 描述 code Int 错误码，成功=0 sid String 请求唯一 id，用于问题定位 desc String 结果描述 data Object 返回结果 # 4、获取文档总结/概要信息 # 接口描述查询文档总结/概要信息 # 接口地址 https://chatdoc.xfyun.cn/openapi/v1/file/summary/query # 请求参数说明 POST，multipart/form-data 字段名 类型 描述 必须 默认值 fileId String 文件 ID Y # 返回参数示例 { "flag": true, "sid": "9746244f046340e2869630e5f6fe8daa", "code": 0, "desc": null, "data": null } # 返回参数说明 字段名 类型 描述 code Int 错误码，成功=0 sid String 请求唯一 id，用于问题定位 desc String 结果描述 data Object 返回结果 # 5、高级功能星火知识库服务还提供 自定义切分、OCR 识别、文档内容查询、内容相似度检索等功能，请参考详细文档：星火知识库API V2.0 # 四、错误码 错误码 描述 处理方式 10019 问答的问题或引用文段可能涉政 检查问题或文件内容 10013 问答的问题或引用文段有敏感违规信息 检查问题或文件内容 10014 问答的输出有敏感违规信息 尝试换个问法 60001 文件类型不对 检查文件 60002 文件大小超限 检查文件 60003 文件上传失败 排查 60005 无文件权限 检查入参 60011 文件字数超限 检查文件 60012 文件无有校字符 检查文件 60005 无文件权限 检查入参 60014 问答的时候未传入文件 id 检查入参 62001 问答的时候，未找到相关文本段 检查提问问题 68003 操作太过频繁 自查 99999 内部错误 排查 # 五、调用示例星火知识库 DEMO - JAVA 星火知识库 DEMO - PYTHON 注： 也欢迎热心的开发者到 讯飞开放平台社区 分享你们的 demo。 # 六、常见问题 # 文档知识库的主要功能是什么？答：让大模型根据文档内容回答问题，更可创建知识库聚合多文档，一次提问遍历领域知识；文档太多难以通读，快用文档总结，自动总结文档概要，快速了解文档内容等。 # 文档知识库现在支持哪些格式的文档？答：目前支持 Word、PDF、Markdown、txt 格式的文档。 # 文档知识库支持什么应用平台？答：目前支持 WebAPI 应用平台。 |
| CopyRight 2018-2019 办公设备维修网 版权所有 豫ICP备15022753号-3 |